Versions XObject for Windows ---------------------------- Version 1.1, 8/9/96 Copyright © 1996 Glenn M. Picher, Dirigo Multimedia Email: gpicher@maine.com Phone: 207/767-8015 Web: http://www.maine.com/shops/gpicher Distributor of registered version --------------------------------- g/matter, inc. Email: support@gmatter.com Web: http://www.gmatter.com Phone: (415)243-0394 Detecting version, directory and file information with Versions --------------------------------------------------------------- The Versions XObject for Windows detects QuickTime, DOS, Windows and file versions. It's able to detect both Win16 and Win32 versions and directories. It's also able to convert between MS-DOS short file names and Windows 95 / Windows NT long file names. You can use the XObject for free to detect QuickTime version numbers (both for 16-bit QuickTime and 32-bit QuickTime). You'll need to register the XObject to use any of the other methods without showing the copyright notice alert box. The Versions XObject works with both Director 4 and Director 5. Even when running under Director 4 (always 16-bit) and under Director 5's 16-bit projectors, or the Director 5's 16-bit authoring environment, the XObject is able to detect 32-bit version information by loading a small 32-bit application and 32-bit .DLL file (included with the XObject, and located in the same directory). Sample cut-and-paste Lingo handlers are provided in the Director 4 testbed movie that's provided with the XObject (using the method names without the initial "m", to match exactly the syntax of global handler names in the planned release of a Lingo Xtra version duplicating this XObject's functionality). You literally only need to cut and paste one script castmember and make sure the required files are in the right directory in order to start using this XObject immediately. You needn't actually write any Lingo code to interface with the XObject directly. The Director 4 testbed movie opens and works fine without modification in Director 5. In addition to testing all methods, there are also sample buttons to decide whether to install or update QuickTime; to check the version number of the appropriate 16-bit or 32-bit version of the primary Video for Windows file, MSVIDEO.DLL, in the appropriate System directory; a button to determine the appropriate 32-bit System directory (which is a different directory that the 16-bit System directory under Windows NT); and a button to identify the first shortcut in the Windows 95 Accessories menu (which demonstrates the short / long file name conversion methods). This XObject has been tested under Window 3.1, Windows 95 and Windows NT. The only current limitation is that Director 5 is not able to use inherently 16-bit XObjects from 32-bit projectors or the 32-bit authoring environment under Windows NT; I anticipate releasing an .x32 Lingo Xtra version of this XObject soon to evade that restriction. This XObject works fine with 16-bit Director 5 projectors, or Director 4's authoring environment and projectors, under Windows NT. Unfortunately, the 16-bit Director 5 authoring environment doesn't run under Windows NT, so you have to do your Windows NT authoring on another non-NT Windows machine if you want to use XObjects with Director 5. The Versions XObject's registered version is distributed by g/matter, inc. in San Francisco. Contact information is above. Versions is one of several plug-ins that are useful in designing CDs that install and run automatcially on both Mac and Windows. Check my Web site again soon for other installation tools. New version information ----------------------- Version 1.0 of this XObject checked the 16-bit QuickTime version within the XObject code itself (i.e., within Versions.DLL). However, field reports indicated that Director 4 and 16-bit Director 5 would sometimes get confused about the state of QuickTime (which the XObject could affect), and would sometimes crash. Therefore, version 1.1 completely insulates the QuickTime code from the Director application itself by locating it in Vers16.DLL, which is loaded by Ask16.EXE when the mQuickTimeVersion method is used. Be sure to distribute those two additional files when you upgrade to this version of the XObject. New to version 1.1 of this XObject are the mGetShortFileName and mGetLongFileName methods, which allow you to convert between MS-DOS style '8.3' short file names and Windows 95 / Windows NT style long file names (which can contain characters such as spaces that are illegal in MS-DOS filenames). This may be necessary if you're checking file versions of a known long-name file, or within a known long-name directory. These methods can also be helpful when using XObjects that are not aware of and don't work with long file names. Also new to version 1.1 is the mWinNTVersion method, which lets you check whick version of Windows NT your code is running under: Workstation, Server, or Advanced Server. mDescribe documentation ----------------------- Here's the XObject's complete table of methods, which provides some minimal documentation. This is also available in Director's Message window, as usual, by sending an mDescribe message to the name of the XObject factory; that is, by typing... Versions(mDescribe) Versions(mDescribe) -- Versions XObject, version 1.1, 8/9/96 Versions -- Copyright © 1996 Glenn M. Picher, Dirigo Multimedia -- Email: gpicher@maine.com -- Web: http://www.maine.com/shops/gpicher -- Phone: (207)767-8015 (South Portland, Maine, USA) -- -- Distributors: g/matter, inc. -- Email: support@gmatter.com -- Web: http://www.gmatter.com -- Phone: (415)243-0394 (San Francisco, California USA) -- -- License granted to use and redistribute for any purpose, -- as long as copyright and contact information remains intact. -- Each instance of the XObject will present a copyright alert -- box once if you use any methods other than the QuickTime version -- checking functions. The registered version does not present any -- alert boxes. -- I mNew -- Standard creation method X mDispose -- Standard dispose method S mQuickTimeVersion -- Get string of QuickTime version ('000000.000000.000000.000000' if QTW -- is not installed). Suitable for string comparisons (<, =, >). Example: -- Your title includes the QTW v2.1.1.57 installer, and you're running on -- a machine with QTW v2.0.1.41 already installed. QTW v. 2.1.1.57 becomes -- '000002.000001.000001.000057' . Alphabetically, this comes after QTW -- v. 2.0.1.41 ('000002.000000.000001.000041'). Thus you can conclude -- that QuickTime needs to be updated to the version supplied with your -- title. This is a workaround for a bug in MCI 'info qtwvideo version' -- reporting, which does not always produce valid numeric comparisons. Only -- reports the 16-bit QuickTime version. Works by initializing QuickTime, -- so the first use may take much longer than subsequent uses. -- Number is formatted to be compatible with file version numbers. -- Note: requires ASK16.EXE and VERS16.DLL in the same directory as this -- XObject .DLL (these files are distributed with this XObject). -- Returns EMPTY if ASK16.EXE can't load; Returns string with word 1 'Error:' -- if ASK16.EXE fails. ***Note: version 1.0 of this XObject did not use -- ASK16.EXE and VERS16.DLL . To avoid occasional crashes when 16-bit Director -- got confused about the state of QuickTime, this new version keeps -- Director's QuickTime code isolated from this XObject's QuickTime -- code. Be sure to add ASK16.EXE and VERS16.DLL to your -- distributed projects when upgrading to this version of this XObject. S mWin32QuickTimeVersion -- Reports the 32-bit QuickTime version. Requires ASK32.EXE and VERS32.DLL -- in the same directory as this XObject .DLL . These files are -- distributed with this XObject .DLL file. Returns EMPTY if 32-bit -- environment is unavailable, or ASK32.EXE can't load; Returns -- string with word 1 'Error:' if ASK32.EXE fails. SS mFileVersion, fileName -- Get string of file version number. Allows checking versions of -- QuickTime compressor files, even 32-bit versions. Suitable for string -- comparisons. Example: QTIM32.DLL in the System folder, v. 2.1.1.57 becomes -- '000002.000001.000001.000057' . The extra digits are the minimum required to -- represent the maximum 64-bit version number. Can be used with any file that -- contains a version resource, not just QuickTime files. If file is missing -- or does not contain version info, result is '000000.000000.000000.000000' . -- Works whether 32-bit environment is available or not; however, -- ASK32.EXE and VERS32.DLL are required in the same directory as this -- XObject .DLL to get Win32 version numbers under Windows NT or 95. These -- files are distributed with this XObject .DLL file. Further note: Windows -- NT uses a different system directory for 32-bit .DLLs. See below. S mWindowsDirectory -- Returns full path to Windows directory (including trailing '\'). -- Useful for building full path names for use with mFileVersion. -- Word 1 of the returned string will be 'Error:' in the unlikely -- event of an error, followed by a description of the error. -- Note: returns the Win16 answer (see below). S mWin32WindowsDirectory -- Returns full path to Windows directory (including trailing '\'). -- Should be the same answer as mWindowsDirectory for all current -- Windows versions, but this may change in future Win versions. -- Note: requires ASK32.EXE and VERS32.DLL in the same directory as this -- XObject .DLL (these files are distributed with this XObject). -- Returns EMPTY if 32-bit environment is unavailable, or ASK32.EXE -- can't load; Returns string with word 1 'Error:' if ASK32.EXE fails. S mSystemDirectory -- Returns full path to System directory (including trailing '\'). -- Useful for building full path names for use with mFileVersion. -- Word 1 of the returned string will be 'Error:' in the unlikely -- event of an error, followed by a description of the error. -- Note: returns the Win16 answer (see below). S mWin32SystemDirectory -- Returns full path to System directory (including trailing '\'). -- Under Windows NT, this is a different answer than mSystemDirectory. -- Note: requires ASK32.EXE and VERS32.DLL in the same directory as this -- XObject .DLL (these files are distributed with this XObject). -- Returns EMPTY if 32-bit environment is unavailable, or ASK32.EXE -- can't load; Returns string with word 1 'Error:' if ASK32.EXE fails. S mDOSVersion -- Returns the DOS version reported to 16-bit apps. No Win32 equivalent. S mWindowsVersion -- Returns the Windows version reported to 16-bit apps. This is -- not the same answer as mWin32Version under Windows 95. S mWin32Version -- Returns the Win32 version (a different answer than mWindowsVersion) -- Note: requires ASK32.EXE and VERS32.DLL in the same directory as this -- XObject .DLL (these files are distributed with this XObject). -- Returns EMPTY if 32-bit environment is unavailable, or ASK32.EXE -- can't load; Returns string with word 1 'Error:' if ASK32.EXE fails. -- Note the lack of ability to check for Win32-specific DOS version. S mWin32Platform -- Returns the Win32 platform ('Win32s on Windows 3.1', -- 'Win32 on Windows 95', or 'Windows NT'). -- Note: requires ASK32.EXE and VERS32.DLL in the same directory as this -- XObject .DLL (these files are distributed with this XObject). -- Returns EMPTY if 32-bit environment is unavailable, or ASK32.EXE -- can't load; Returns string with word 1 'Error:' if ASK32.EXE fails. S mWin32Build -- Returns the Win32 build. This is useful because Director requires -- at least Windows NT v3.51 with Service Pack 4 applied (build 1057). -- Note: requires ASK32.EXE and VERS32.DLL in the same directory as this -- XObject .DLL (these files are distributed with this XObject). -- Returns EMPTY if 32-bit environment is unavailable, or ASK32.EXE -- can't load; Returns string with word 1 'Error:' if ASK32.EXE fails. S mWinNTVersion -- Tells you what verison of Windows NT you're running under-- 'Workstation', -- 'Server', 'Advanced Server', 'Unknown', or 'Error' is there's a problem. -- Note: requires ASK32.EXE and VERS32.DLL in the same directory as this -- XObject .DLL (these files are distributed with this XObject). -- Returns EMPTY if 32-bit environment is unavailable, or ASK32.EXE -- can't load; Returns string with word 1 'Error:' if ASK32.EXE fails. SS mGetShortFileName, theFile -- Returns the MS-DOS style filename of a Windows 95 or Windows NT long -- file name which might contain spaces or other DOS-illegal characters. -- This method can also accept file names that are already DOS-legal. -- This method is helpful when an XObject only works with DOS filenames. -- Note: requires ASK32.EXE and FNAME32.DLL in the same directory as this -- XObject .DLL (these files are distributed with this XObject). -- Returns EMPTY if 32-bit environment is unavailable, or ASK32.EXE -- can't load; Returns string with word 1 'Error:' if ASK32.EXE fails. SS mGetLongFileName, theFile -- Returns the Windows 95 or Windows NT long file name, which might contain -- spaces or other DOS-illegal characters, given a DOS short file name. -- This method can also accept file names that are already long. -- Note: requires ASK32.EXE and FNAME32.DLL in the same directory as this -- XObject .DLL (these files are distributed with this XObject). -- Returns EMPTY if 32-bit environment is unavailable, or ASK32.EXE -- can't load; Returns string with word 1 'Error:' if ASK32.EXE fails. -- Of historical interest: Why the Versions XObject? ------------------------------------------------- Initially, the Versions XObject was created to work around a bug in the MCI interface to QuickTime for Windows. When requesting QuickTime version numbers using... mci "info qtwvideo version" put the result ...the reported number would not report decimal point placement consistently across different version of QuickTime for Windows. This made it rather difficult to determine whether the user should update QuickTime with the version of the QuickTime for Windows installer you provided with your title. However, the question of version numbers proved more subtle with Apple's introduction of 16-bit and 32-bit flavors of QuickTime for Windows beginning with version 2.1.1 in the spring of 1996. It's only possible to detect the 16-bit QuickTime version from a 16-bit app or .dll, and you can only know the 32-bit QuickTime version from a 32-bit app or .dll . XObjects are inherently 16-bit code, and so always return a 16-bit answer to questions such as these. To make things more confusing, the MCI interface to QuickTime for Windows could report a 16-bit version number to a 32-bit application (Director 5), even though the application, using the C rather than the MCI interface to QuickTime, required the 32-bit version. The mFileVersion method was intended to work around this limitation by checking for a file version resource in particularly named files in the System directory (such as QTIM32.DLL). However, there are a number of problems with this approach. The existence of a file alone does not confirm proper configuration. Furthermore, certain .DLLs have file version resources that can only be read from 32-bit code running on a 32-bit platform (such as WIndows NT system files); they can't be identified from 16-bit code. Finally, Windows NT places 32-bit .DLL files into a different directory than 16-bit .DLLs, and the name of that directory can only be detected from 32-bit code. The solution was to write a 32-bit application which called a 32-bit .DLL to get 32-bit answers to these configuration questions. This 32-bit application (Ask32.exe) is launched by the 16-bit XObject .DLL file, and the two tasks communicate with each other to access the requested information. Ask32.exe and Vers32.dll must be distributed in the same directory as Versions.dll to work properly on Win32 platforms such as Windows 95 and Windows NT. Known bugs: ----------- None. Known limitations: ------------------ Does not operate under Windows NT with 32-bit Director 5's authoring environment or Director 5's 32-bit projector. This is true of any XObject. This XObject should be used in an initial Director movie that does *not* contain any QuickTime castmembers. Director itself will display an ungraceful message about the need for QuickTime when a movie is loaded, if any QuickTime castmember are found in the movie, *before* you get a chance to use the Versions XObject. The QuickTime version methods are rather slow, because not only do they fully initialize QuickTime and all its .DLL files, but the code itself is run from a separate .EXE file loaded by this XObject. Little can be done to speed this process up. Revision history: ----------------- 8/9/96: Version 1.1 Isolated QuickTime code from Director's code in mQuickTimeVersion method by using Ask16.EXE and Vers16.DLL . This eliminates some confusion and possible crashes when Versions was used from 16-bit Director executables. Added mGetShortFileName, mGetLongFileName, and mWinNTVersion methods. Added more information to Read Me document. 6/26/96: Version 1.0 16 and 32 bit methods. 6/8/96: Version 0.9 beta 16-bit only methods. Standard legal disclaimer ------------------------- This software is provided "as is" without warranty of any kind, either expressed or implied, including, but not limited to, the implied warranties of merchantability or fitness for a particular purpose. The software or its documentation or sample code may include errors or technical inaccuracies. Changes are periodically made to this software, its documentation and sample code, and may be incorporated in new versions. Dirigo Multimedia and g/matter may improve or change their products at any time without notice. Dirigo Multimedia and g/matter assume no responsibility for and disclaim all liability for errors in this software or its documentation and sample code. Neither Dirigo Multimedia nor g/matter will be responsible for any damages of any sort under any conditions. While the Versions XObject contains no known bugs, use it at your own risk. As always, you should make frequent backups of important information. Some jurisdictions do not allow the exclusion of implied warranties, so the above exclusion may not apply to you.